/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.vfs;
import java.io.File;
/**
* A file system, made up of a hierarchy of files.
*
* @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
* @version $Revision: 484648 $ $Date: 2006-12-08 17:18:36 +0100 (Fr, 08 Dez 2006) $
*/
public interface FileSystem
{
/**
* Returns the root file of this file system.
*/
FileObject getRoot() throws FileSystemException;
/**
* Returns the name of the root file of this file system.
*/
FileName getRootName();
/**
* Determines if this file system has a particular capability.
*
* @param capability The capability to check for.
* @return true if this filesystem has the requested capability.
* Note that not all files in the file system may have the
* capability.
* @todo Move this to another interface, so that set of capabilities can be queried.
*/
boolean hasCapability(Capability capability);
/**
* Returns the parent layer if this is a layered file system.
*
* @return The parent layer, or null if this is not a layered file system.
*/
FileObject getParentLayer() throws FileSystemException;
/**
* Gets the value of an attribute of the file system.
* <p/>
* <p>TODO - change to <code>Map getAttributes()</code> instead?
* <p/>
* <p>TODO - define the standard attribute names, and define which attrs
* are guaranteed to be present.
*
* @param attrName The name of the attribute.
* @return The value of the attribute.
* @throws org.apache.commons.vfs.FileSystemException
* If the file does not exist, or is being written, or if the
* attribute is unknown.
* @see org.apache.commons.vfs.FileContent#getAttribute
*/
Object getAttribute(String attrName) throws FileSystemException;
/**
* Sets the value of an attribute of the file's content. Creates the
* file if it does not exist.
*
* @param attrName The name of the attribute.
* @param value The value of the attribute.
* @throws FileSystemException If the file is read-only, or is being read, or if the attribute
* is not supported, or on error setting the attribute.
* @see FileContent#setAttribute
*/
void setAttribute(String attrName, Object value)
throws FileSystemException;
/**
* Finds a file in this file system.
*
* @param name The name of the file.
* @return The file. Never returns null.
*/
FileObject resolveFile(FileName name) throws FileSystemException;
/**
* Finds a file in this file system.
*
* @param name The name of the file. This must be an absolute path.
* @return The file. Never returns null.
*/
FileObject resolveFile(String name) throws FileSystemException;
/**
* Adds a listener on a file in this file system.
*
* @param file The file to attach the listener to.
* @param listener The listener to add.
*/
void addListener(FileObject file, FileListener listener);
/**
* Removes a listener from a file in this file system.
*
* @param file The file to remove the listener from.
* @param listener The listener to remove.
*/
void removeListener(FileObject file, FileListener listener);
/**
* Adds a junction to this file system. A junction is a link that attaches
* the supplied file to a point in this file system, making it look like
* part of the file system.
*
* @param junctionPoint The point in this file system to add the junction.
* @param targetFile The file to link to.
* @throws FileSystemException If this file system does not support junctions, or the junction
* point or target file is invalid (the file system may not support
* nested junctions, for example).
*/
void addJunction(String junctionPoint, FileObject targetFile)
throws FileSystemException;
/**
* Removes a junction from this file system.
*
* @param junctionPoint The junction to remove.
* @throws FileSystemException On error removing the junction.
*/
void removeJunction(String junctionPoint) throws FileSystemException;
/**
* Creates a temporary local copy of a file and its descendents. If
* this file is already a local file, a copy is not made.
* <p/>
* <p>Note that the local copy may include additonal files, that were
* not selected by the given selector.
*
* @param file The file to replicate.
* @param selector The selector to use to select the files to replicate.
* @return The local copy of this file.
* @throws FileSystemException If this file does not exist, or on error replicating the file.
* @todo Add options to indicate whether the caller is happy to deal with
* extra files being present locally (eg if the file has been
* replicated previously), or whether the caller expects only
* the selected files to be present.
*/
File replicateFile(FileObject file, FileSelector selector)
throws FileSystemException;
/**
* Returns the FileSystemOptions used to instantiate this filesystem
*/
FileSystemOptions getFileSystemOptions();
/**
* Returns a reference to the FileSytemManager
*/
FileSystemManager getFileSystemManager();
/**
* Returns the accuracy of the last modification time
*
* @return ms 0 perfectly accurate, >0 might be off by this value e.g. sftp 1000ms
*/
double getLastModTimeAccuracy();
}